.\" Man page for the libdmtx project.
.\"
.\" To view: $ groff -man -T ascii libdmtx.3 | less
.\" To text: $ groff -man -T ascii libdmtx.3 | col -b | expand
.\"
.TH LIBDMTX 3 "June 2, 2011"
.SH NAME
libdmtx \- Data Matrix Encoding & Decoding Library 0.7.4
.SH SYNOPSIS
\fB#include <dmtx.h>\fP

cc file.c -ldmtx

.SH DESCRIPTION
\fIlibdmtx\fP is a software library that enables programs to read and write Data Matrix barcodes of the modern ECC200 variety. The library runs natively on several platforms, and can be accessed by multiple languages using the libdmtx language wrappers. The utility programs \fIdmtxread\fP and \fIdmtxwrite\fP provide a command line interface for libdmtx, and serve as a good reference for developers writing their own libdmtx-enabled programs.

Data Matrix barcodes store data as a pattern of ON and OFF modules (often black on white) in a grid pattern that resembles a checkerboard. Like other 2D symbologies, Data Matrix barcodes have a large data capacity compared to their traditional 1D cousins, and employ sophisticated error correction techniques. Data Matrix barcodes can be square or rectangle in shape, and offer several encodation schemes for optimized storage of text and/or binary data. The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix.

.SH ENCODING - Generating Data Matrix Barcodes
C/C++ programs can generate a barcode with just a few basic calls to libdmtx:

1. Call \fBdmtxEncodeCreate()\fP

Creates a new \fBDmtxEncode\fP structure and initializes the encoding process. This function must be called before using the other encoding functions.

2. Call \fBdmtxEncodeSetProp()\fP [optional]

Allows you to control specific aspects of the encoding behavior. If this function is not called, libdmtx will use the defaults set by \fBdmtxEncodeCreate()\fP above. The complementary function, \fBdmtxEncodeGetProp()\fP, allows you to detect the current settings.

3. Call either \fBdmtxEncodeDataMatrix()\fP or \fBdmtxEncodeDataMosaic()\fP

Call one of these functions to generate an image of the desired barcode type. Your program is responsible for dispatching the resulting output to its destination, whether that means displaying it on a screen, writing an image file, copying it elsewhere, etc...

4. Call \fBdmtxEncodeDestroy()\fP

Releases memory allocated during the encoding process.

.SH DECODING - Reading Data Matrix Barcodes
Barcode reading takes more steps than barcode generation, mainly because libdmtx must find a barcode region before it can decode the message. However, this too is a relatively simple process that uses 4 main structures:

\fBDmtxImage\fP holds image properties and a pointer to pixel data held by the calling program.

\fBDmtxDecode\fP holds values for controlling decode behavior and tracking scan progress. When scanning a new image, calling programs should always create a new \fBDmtxDecode\fP structure instead of reusing an old one.

\fBDmtxRegion\fP defines a 4-sided region in pixel coordinates. Regions may be found in almost any orientation, and their corners won't necessarily form right angles. libdmtx uses this structure to store the location of potential barcodes, which are then returned to the calling program one-at-a-time.

\fBDmtxMessage\fP holds the decoded message after being extracted from the barcode region. A successfully decoded region will produce exactly one message.

Use the following functions to find and decode Data Matrix barcodes:

1. Call \fBdmtxImageCreate()\fP

Creates and initializes a new \fBDmtxImage\fP structure using pixel data provided by the calling application. Parameters include a pointer to the existing pixel array, image width, height, and the pixel packing format.

2. Call \fBdmtxImageSetProp()\fP [optional]

Sets image properties to control the pixel mapping logic. These settings allow libdmtx to understand many native in-memory image layouts, thus preventing the extra work of transforming and copying data to a one-size-fits-all format. A \fBdmtxDecodeGetProp()\fP function is also available for detecting the current image properties.

3. Call \fBdmtxDecodeCreate()\fP

Creates and initializes a new \fBDmtxDecode\fP struct, which designates the image to be scanned and initializes the scan grid pattern. This function must be called before any other scanning functions.

4. Call \fBdmtxDecodeSetProp()\fP [optional]

Sets internal properties to control decoding behavior. This feature allows you to optimize performance and accuracy for specific image conditions. A \fBdmtxDecodeGetProp()\fP function is also available.

5. Call \fBdmtxRegionFindNext()\fP

Searches every pixel location in a grid pattern looking for potential barcode regions. A \fBDmtxRegion\fP is returned whenever a potential barcode region is found, or if the final pixel location has been scanned. Subsequent calls to this function will resume the search where the previous call left off.

6. Call either \fBdmtxDecodeMatrixRegion()\fP or \fBdmtxDecodeMosaicRegion()\fP

Extracts raw data from the barcode region and decodes the underlying message.

7. Call \fBdmtxMessageDestroy()\fP

Releases memory held by a \fBDmtxMessage\fP struct. The complementary function, \fBdmtxMessageCreate()\fP, is automatically called by \fBdmtxDecodeMatrixRegion()\fP and therefore is not normally used by the calling program.

8. Call \fBdmtxRegionDestroy()\fP

Releases memory held by a \fBDmtxRegion\fP struct. The complementary function, \fBdmtxRegionCreate()\fP, is automatically called by \fBdmtxRegionFindNext()\fP (actually \fBdmtxRegionScanPixel()\fP) and therefore is not normally used by the calling program.

9. Call \fBdmtxDecodeDestroy()\fP

Releases memory held by a \fBDmtxDecode\fP struct. This is the complementary function to \fBdmtxDecodeCreate()\fP.

10. Call \fBdmtxImageDestroy()\fP

Releases memory held by a \fBDmtxImage\fP struct, excluding the pixel array passed to \fBdmtxImageCreate()\fP. The calling program is responsible for releasing the pixel array memory, if required.

.SH EXAMPLE PROGRAM

This example program (available as simple_test.c in the source package) demonstrates \fIlibdmtx\fP functionality in both directions: encoding and decoding. It creates a Data Matrix barcode in memory, reads it back, and prints the decoded message. The final output message should match the original input string.

  #include <stdlib.h>
  #include <stdio.h>
  #include <string.h>
  #include <assert.h>
  #include <dmtx.h>

  int
  main(int argc, char *argv[])
  {
     size_t          width, height, bytesPerPixel;
     unsigned char   str[] = "30Q324343430794<OQQ";
     unsigned char  *pxl;
     DmtxEncode     *enc;
     DmtxImage      *img;
     DmtxDecode     *dec;
     DmtxRegion     *reg;
     DmtxMessage    *msg;

     fprintf(stdout, "input:  \\"%s\\"\\n", str);

     /* 1) ENCODE a new Data Matrix barcode image (in memory only) */

     enc = dmtxEncodeCreate();
     assert(enc != NULL);
     dmtxEncodeDataMatrix(enc, strlen(str), str);

     /* 2) COPY the new image data before releasing encoding memory */

     width = dmtxImageGetProp(enc->image, DmtxPropWidth);
     height = dmtxImageGetProp(enc->image, DmtxPropHeight);
     bytesPerPixel = dmtxImageGetProp(enc->image, DmtxPropBytesPerPixel);

     pxl = (unsigned char *)malloc(width * height * bytesPerPixel);
     assert(pxl != NULL);
     memcpy(pxl, enc->image->pxl, width * height * bytesPerPixel);

     dmtxEncodeDestroy(&enc);

     /* 3) DECODE the Data Matrix barcode from the copied image */

     img = dmtxImageCreate(pxl, width, height, DmtxPack24bppRGB);
     assert(img != NULL);

     dec = dmtxDecodeCreate(img, 1);
     assert(dec != NULL);

     reg = dmtxRegionFindNext(dec, NULL);
     if(reg != NULL) {
        msg = dmtxDecodeMatrixRegion(dec, reg, DmtxUndefined);
        if(msg != NULL) {
           fputs("output: \\"", stdout);
           fwrite(msg->output, sizeof(unsigned char), msg->outputIdx, stdout);
           fputs("\\"\\n", stdout);
           dmtxMessageDestroy(&msg);
        }
        dmtxRegionDestroy(&reg);
     }

     dmtxDecodeDestroy(&dec);
     dmtxImageDestroy(&img);
     free(pxl);

     exit(0);
  }

.SH "SEE ALSO"
\fIdmtxread\fP(1), \fIdmtxwrite\fP(1), \fIdmtxquery\fP(1)
.SH STANDARDS
ISO/IEC 16022:2000
.PP
ANSI/AIM BC11 ISS
.SH BUGS
Email bug reports to mike@dragonflylogic.com
.SH AUTHOR
Copyright (C) 2008, 2009 Mike Laughton
.\" end of man page
